Aminet 21

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / mus / misc / ExoticRip32.lha / ExoticRipper / DOC / Unpack-Library / UnpackLib_Docs < prev next >

Wrap

Text File | 1995-12-29 | 30.2 KB | 843 lines

*************************************************************************** * UNPACK.LIBRARY V40.56 DOC * * * * * * Update 17-05-95 * * * * * * SAFE HEX INTERNATIONAL * *************************************************************************** Welcome to the release version of this library. I hope it's a library you can use in your virus killer or whatever you are doing. One of the things this library can do, is to help a viruskiller programmer to scan files that are crunched. o This library is copyrighted by SHI and may NOT be used in commercial programs without a written permission from SHI. o SHI members can of course use this library for free. (But remember to get a written permission. o All Shareware programmers can be SHI members, if they full-fill to support our anti-virus work. (But remember to send your address and program idea to SHI, to get a written permission). It's forbidden to reassemble (reverse engining) in any way this library code. All the ideas to the way we unpacks files are copyrighted by SHI. If you don't respect our copyright - or, if you use this library without a written permission, SHI will contact the police to stop you. Please add the "WantedHelp" (a list containing wanted crunchers for update), and remember to credit the author (Thomas Neumann) and SHI in your program as stated in the following: --------------------------------------------------------------------------- ABOUT SAFE HEX INTERNATIONAL If you know a virus programmer you can get a reward of $ 1000 for supplying his name and address. The fact is that the law punishes data crime very severely. (5 years in jail in most countries). We are an international group with more than 500 members who have started trying to stop the spread of virus. Let me give you some example: 1. Our motto is: "Safe Hex", who dares do anything else today?". 2. A virus bank containing more than 1800 Amiga and PC viruses for supporting good shareware antivirus programs. 3. We help people to get money back lost by virus infection. 4. We write articles about virus problems for about 20 computer magazines worldwide. 5. We release the newest and the best virus killers around from about 25 wellknown programmers worldwide. 6. We have more than 35 PC and Amiga "Virus Centers" worldwide where you can get free virus help by phoning our "Hotline", and the newest killers translated in your own language at very little cost. For more information contact: SAFE HEX INTERNATIONAL (Please send 2 "Coupon-Response Erik Loevendahl Soerensen International" and a self addres- Snaphanevej 10 sed envelope, if you want infor- DK-4720 Praestoe mation about SHI by letter). Denmark Phone: + 45 55 99 25 12 Fax : + 45 55 99 34 98 --------------------------------------------------------------------------- *************************************************************************** * Table of contents * *************************************************************************** unpack.library/upAllocCInfo() unpack.library/upDetermineFile() unpack.library/upFreeCInfo() unpack.library/upFreeFile() unpack.library/upLoadFile() unpack.library/upNewUnpackNum() unpack.library/upSendCmd() unpack.library/upTestHunk() unpack.library/upUnpack() unpack.library/upUnpackList() unpack.library/upUnpackListNext() unpack.library/upUnuseDrive() unpack.library/upUseDrive() --------------------------------------------------------------------------- *************************************************************************** * Offsets and functions destiptions * *************************************************************************** upAllocCInfo(34.0) upAllocCInfo(34.0) NAME upAllocCInfo - allocates an info structure. SYNOPSIS info = upAllocCInfo () D0 -30 APTR upAllocCInfo(VOID); FUNCTION upAllocCInfo() allocates an info structure the library uses when it unpacks files. You just have to call this function in the beginning of your program and then free it again with FreeCInfo() at the end. I have made this function, because in future versions of this library, the structure will be bigger. Your program will then be compatible for any future versions of this library. INPUTS None. OUTPUTS info - is a pointer to the allocated info structure. If there has occured an error, a zero is returned. STRUCTURE This is how the Info Structure is build: STRUCTURE UnpackInfo,0 APTR UI_Filename APTR UI_Path APTR UI_Jump APTR UI_CruncherName APTR UI_DecrunchAdr LONG UI_DecrunchLen UWORD UI_ErrorNum UWORD UI_CrunchNum UBYTE UI_CrunchType UBYTE UI_Flag APTR UI_LoadNamePoi LONG UI_CrunchLen APTR UI_UserData ;V35+ APTR UI_TrackJump ;V36+ APTR UI_TrkErrJump ;V36+ LONG UI_Offset ;V36+ UWORD UI_Track ;V36+ APTR UI_ErrorMsg ;V37+ APTR UI_CrunchAdr ;V37+ APTR UI_LhaPattern ;V38+ BOOL8 UI_UseFilenamePointer ;V39+ ; This Is Private, Do NOT Touch UBYTE UI_Pad LONG UI_CrunchLenTemp LONG UI_FileHandler LONG UI_Lock LONG UI_OldLock APTR UI_InfoAdr APTR UI_UnpackPoi ULONG UI_Temp STRUCT UI_Data,4*4 ;V35+ STRUCT UI_LoadName,128 STRUCT UI_ExecuteString,256 LABEL UnpackInfo_SIZEOF NOTE: ----- The private area is a bad idea to use, because the different fields will maybe be moved around in future versions. UI_Filename is a pointer to the filename you want to scan. UI_Path is a pointer to a zero-terminated path where the library have to unpack archive files, such as a LHA archive. Please select a path where you haven't got some important data, because ALL files will be deleted in the path if the DELETE flag is on. UI_Jump This is a pointer to your scan routine. If this pointer are zero, no jump will be made. UI_CruncherName This is a pointer to the crunchers name the file is crunched with. The name are zero-terminated. UI_DecrunchAdr This is the start address of the decrunched file. Your scan routine just have to read this field and the UI_DecrunchLen field and scan that memory. UI_DecrunchLen This is the length of the decrunched file. UI_ErrorNum If an error occur, the error number is stored in this field. See the unpack.i file for more information. UI_CrunchNum Here is the cruncher number stored. Each cruncher has a number so you can find out which cruncher there are used on the file. UI_CrunchType Here is a number that tells about the file (archive, data or object file). Bit 7 indicate that the file are encrypted. It will be set after the call to DetermineFile() function. UI_Flag You can select some different things the library has to do when it tests the file. See below for more info. UI_LoadNamePoi This is just a pointer to the UI_LoadName field. Use this if you want to use the UI_LoadName field, because the field will be moved in future versions. UI_LoadName Here is the filename stored, the library is about to decrunch, if the file is an archive. UI_CrunchLen This is the length of the crunched file. UI_UserData This value will be stored in A1 when the Unpack() function jump through the UI_Jump field. (V35+) UI_TrackJump This field have the same function as UI_Jump, exept that the library will only jump through this field when its unpack a track crunched file, such as DMS. The library will jump for every track it unpacks. You have to return a return value in D0. You can select between these values: 0 means every thing are okay, just continue and -1 means stop unpacking. If this field are zero, no jump will be made (V36+). UI_TrkErrJump The library will jump through this pointer if an error occurs. There are a lot of errors, such as checksum error etc. You routine can read the UI_ErrorNum field in the info structure to see what went wrong. In D0 you have to return the same values as in UI_TrackJump (V36+). UI_Offset Here will be stored the offset on a disk, ex. if the library just have unpacked track 40, there will be stored in this field: 40*22*512. You tracksave routine can read this field, UI_DecrunchAdr and the UI_DecrunchLen fields and just call the SendCmd() function with these values as parameters (V36+). UI_Track Here are stored the track the library just have unpacked (V36+). UI_ErrorMsg If an error occurs, a pointer to the error message will be stored here (V37+). UI_CrunchAdr This is a pointer to the crunched data. If you use the NoLoad flag, you have to store the start address and the length of the crunched data in this field and the UI_CrunchLen field (V37+). UI_LhaPattern Here can you store a pointer to a Lha pattern. This means, the zero-terminated string this pointer points to, will be copied at the end of the execute string. If you ex. have a string containing: "a#?", the unpack.library will only unpack all files starting with an "a". Zero in this pointer means no pattern (V38+). NOTE: This pointer will be ignored if you have set the UFB_OneFile bit in the UI_Flag. UI_UseFilenamePointer This boolean flag will be set to true, when you must use the filename pointed to with UI_LoadNamePoi. If false, you have to use you own filename. This flag will be set to true when unpacking a file in an archive and the file type is not an archive. See example (V39+). The flag have the following functions: Name Bit Function --------------------------------------------------------------------------- UFB_OneFile 0 Select to unpack one file at a time or the whole archive. If set, one file is selected. UFB_Delete 1 Delete files after scanning. Set = Delete. If you set this bit on, ALL files AND directories will be deleted, not only the files there were stored in the archive. UFB_NoFree 2 If this bit is set, the decrunched file will NOT be freed from memory after the Unpack() function have called through the UI_Jump pointer. If you set this bit, you have to free the memory by yourself with the FreeFile() function. (V35+) UFB_Banner 3 This bit are the give banner bit. If set, you will get the banner text in UI_DecrunchAdr. Your routine the UI_TrackJump pointer points to, have to test the UI_Offset field to see it's a banner or normal track there are given. If the UI_Offset are -1, its a banner. (V36+) UFB_NoLoad 4 If this bit are set, the DetermineFile() and Unpack() functions will not load the file into memory, but use the UI_CrunchAdr and UI_CrunchLen field in the Unpack Info structure to get the crunched data (V37+). UFB_Protect 5 If you set this bit and the UFB_NoLoad are cleared, the DetermineFile() function will change the protections bit on the file to determine. It will set the RWED bits (V38+). 6-7 Reserved BUGS None known. SEE ALSO upFreeCInfo() --------------------------------------------------------------------------- upDetermineFile(34.0) upDetermineFile(34.0) NAME upDetermineFile - scans a file to find out which cruncher that are used. SYNOPSIS success = upDetermineFile (info, filename) D0 -42 A0 A1 BOOL upDetermineFile (APTR, char *); FUNCTION upDetermineFile() scans a file to find out which cruncher the file are crunched with. If the library can't find out, an error message is returned. You have to call this function first, then the upUnpack() function, if no error has occured. INPUTS info - is the memory address you got from the upAllocCInfo() function. filename - is a pointer to the filename you want to scan. The filename has to be zero-terminated. OUTPUTS success - is an indicator that tells about the operation. If every thing is okay, a non-zero value is returned, else a zero will be returned. If you get an error, you can look at the UI_ErrorNum flag in the info structure to see what went wrong. BUGS None known. SEE ALSO upUnpack() --------------------------------------------------------------------------- upFreeCInfo(34.0) upFreeCInfo(34.0) NAME upFreeCInfo - frees the info structure again. SYNOPSIS upFreeCInfo (info) -36 A0 void upFreeCInfo (APTR); FUNCTION upFreeCInfo() frees the info structure again. You have to call this function at the end of your program. INPUTS info - is the memory address you got from the upAllocCInfo() function. If the memory address is zero, you will NOT take a trip to India (and visit the GURU) when you call this function. OUTPUTS None. BUGS None known. SEE ALSO upAllocCInfo() --------------------------------------------------------------------------- upFreeFile(34.20) upFreeFile(34.20) NAME upFreeFile - frees a file from memory. SYNOPSIS upFreeFile (info) -84 A0 void upFreeFile (APTR); FUNCTION You have to call this function after you have called the upLoadFile() function and are finished with the file. This function frees the memory again. NOTE: You MUST call this function instead of freeing the memory by yourself!! INPUTS info - is the memory address you got from the upAllocCInfo() function. You can call always this function, even if the upLoadFile() function returned an error. OUTPUTS None. BUGS None known. SEE ALSO upLoadFile() --------------------------------------------------------------------------- upLoadFile(34.20) upLoadFile(34.20) NAME upLoadFile - loads a file into memory. SYNOPSIS success = upLoadFile (info) D0 -78 A0 BOOL upLoadFile (APTR); FUNCTION This function allocate some memory with the files length and loads the file into it. The filename are taken from the UI_Filename field in the info structure. The length and address of the file are stored in UI_DecrunchLen and UI_DecrunchAdr. V36.30: ------- If the library runs under KS 37+, all caches will be cleared after the file are loaded into the memory. INPUTS info - is the memory address you got from the upAllocCInfo() function. OUTPUTS success - is an indicator that tells about the operation. If every thing is okay, the file length is returned, else a zero will be returned and the allocated memory will be freed. If you get an error, you can look at the UI_ErrorNum flag in the info structure to see what went wrong. BUGS None known. SEE ALSO upFreeFile() --------------------------------------------------------------------------- upNewUnpackNum(37.32) upNewUnpackNum(37.32) NAME upNewUnpackNum - gives the number of unpackers in a structure. SYNOPSIS number = upNewUnpackNum () A0 -108 APTR upNewUnpackNum (void); FUNCTION upNewUnpackNum() counts the number of unpackers the library can determine and unpack. You will get two different numbers of unpackers. The first one (types) are the numbers of different types the library can unpack, example PowerPacker Data, PowerPacker Library etc. The second one (unpackers) is the number of unpackers, example PowerPacker, Lha, Imploder etc. INPUTS None. OUTPUTS number - a pointer to a structure that look like this: STRUCTURE NumberStruct,0 UWORD NS_Version ;Library Version UWORD NS_Revision ;Library Revision UWORD NS_Types UWORD NS_Unpackers LABEL NumberStruct_SIZEOF BUGS None known. --------------------------------------------------------------------------- upSendCmd(36.30) upSendCmd(36.30) NAME upSendCmd - sends a command to a devive. SYNOPSIS error = upSendCmd (dinfo, address, offset, length, cmd) D0 -102 A0 A1 D1 D2 D0 UBYTE upSendCmd (APTR, APTR, ULONG, ULONG, UBYTE); FUNCTION The only thing this function does, is send the command with the parameters to the device opened by the upUseDrive() function. The command will be sent by the DoIO() function. INPUTS dinfo - is a pointer returned by the upUseDrive() function. address - is a pointer to the data area. offset - is the offset on the disk. length - is the number of bytes to send. cmd - is the command to send, like a read, write or update. OUTPUTS error - is the error number returned by the device. BUGS None known. SEE ALSO upUseDrive(), upUnuseDrive() --------------------------------------------------------------------------- upTestHunk(34.1) upTestHunk(34.1) NAME upTestHunk - tests the hunk structure in a file. SYNOPSIS success = upTestHunk (address) D0 -54 A0 BOOL upTestHunk (APTR); FUNCTION upTestHunk() tests a file for the hunk structure. You have to be sure, that the file you want to test is an object file, else this routine will return an error. You can check this by look in the UI_CrunchType flag in the info structure. You don't need to call this function by yourself before you calling the upUnpack() function, because the upUnpack() function does that by itself. I'm not quite sure it handles the overlay hunk correctly, but it should handle it. If you find a file you know are okay and this function says it's defect, please send me the file so I can find the error. INPUTS address - is the start address of the file you want to test. OUTPUTS success - is an indicator that tells about the operation. If every thing is okay, a non-zero value is returned, else a zero will be returned. BUGS None known. --------------------------------------------------------------------------- upUnpack(34.0) upUnpack(34.0) NAME upUnpack - unpacks the file. SYNOPSIS success = upUnpack (info) D0 -48 A0 BOOL upUnpack (APTR); FUNCTION upUnpack() loads the file into memory and unpacks it. When the file is unpacked, the library will jump through the UI_Jump pointer to your scan routine. If the UI_Jump contains a zero, the library will not jump. All what your scan routine has to do, is to get the UI_DecrunchAdr and UI_DecrunchLen from the info structure and scan that memory. If the file is an archive (Lha, zoo), the library will unpack the archive and then read one file at a time and jump to your scan routine. If you need a password to unpack a file, the library will open a little window where it asks for the password. The window will be opened on the active screen, so if you open a screen by yourself, the window will appear on it (if it's active). NOTE: ----- After an archive is unpacked and scanned, all the files and directories in the path you have selected will be deleted if the DELETE flag is on, not just the files there were stored in the archive, but ALL files will be deleted, so be sure to use a temp directory or something like that. V35.22: ------- When this function jumps through the UI_Jump pointer, the following registers will have these pointers: A0 = The start address of your routine (Unpack() makes a jsr (a0)). A1 = Your pointer stored in the UI_UserData field. A4 = The start address of the info structure. V36.30: ------- If the library runs under KS V37+, all caches will be cleared after the decrunching. Track Crunched Files: --------------------- This function will jump through UI_TrackJump instead of UI_Jump when it unpacks a track crunched file. Such files are ex. a DMS file. The routine have to return a value in D0. The values can be 0 to indicate that every things are ok and -1 to stop unpacking. V38.40: ------- This function are now made recursive. That means it will call itself until the file can't be decrunched any more. Now it can unpack a lha file in a lha file or a file crunched with imploder and powerpacker etc. If you have ex. select to unpack a lha file at RAM:, the first lha file will be unpacked there. If there are more lha files, the next one will be unpacked in RAM:-xxx/ where xxx is the name of the lha archive etc. NOTE: ----- The recursive process will take a lot of stack and memory. Each time the function will call itself, it will allocate a new info structure and 256 bytes to the new path. INPUTS info - is the memory address you got from the upAllocCInfo() function. OUTPUTS success - is an indicator that tells about the operation. If every thing is okay, a non-zero value is returned, else a zero will be returned. If you get an error, you can look at the UI_ErrorNum flag in the info structure to see what went wrong. BUGS The DMS Deep decruncher will not work correctly. I try to fix this bug as soon as possible. SEE ALSO upDetermineFile(), upAllocCInfo() --------------------------------------------------------------------------- upUnpackList(34.1) upUnpackList(34.1) NAME upUnpackList - makes an unpacker name list. SYNOPSIS name = upUnpackList (info) A1 -66 A0 char * upUnpackList (APTR); FUNCTION upUnpackList() gives a pointer to the first name to a packer the library can determine & unpack. You can use this function, if you want to make a list over all the unpackers the library can determine. Call this function first and then use upUnpackListNext(). INPUTS info - is the memory address you got from the upAllocCInfo() function. OUTPUTS name - is a pointer to a null-terminated string where the first name are stored. BUGS None known. SEE ALSO upUnpackListNext() --------------------------------------------------------------------------- upUnpackListNext(34.1) upUnpackListNext(34.1) NAME upUnpackListNext - reads the next name in the unpacker list. SYNOPSIS success,name = upUnpackListNext (info) D0 A1 -72 A0 BOOL,APTR upUnpackListNext (APTR); FUNCTION upUnpackListNext() gives a pointer to the next name to a packer the library can determine & unpack. You can use this function, if you want to make a list over all the unpackers the library can determine. Call the upUnpackList() function first and then use this function. INPUTS info - is the memory address you got from the upAllocCInfo() function. OUTPUTS name - is a pointer to a null-terminated string where the next name are stored. V37.32 ------ This pointer will also be zero when the success flag are zero. This are only made for C-programmers. success - if this contains a zero, there are no more crunchers in the list. Otherwise it will contain a non-zero value. BUGS None known. SEE ALSO upUnpackList() --------------------------------------------------------------------------- upUnuseDrive(36.30) upUnuseDrive(36.30) NAME upUnuseDrive - give back the drive to DOS. SYNOPSIS upUnuseDrive (dinfo) -96 A0 void upUnuseDrive (APTR); FUNCTION This function closes the device again and make the drive unbusy. INPUTS dinfo - is the pointer returned by the upUseDrive() function. OUTPUTS Nothing. BUGS None known. SEE ALSO upUseDrive(), upSendCmd() --------------------------------------------------------------------------- upUseDrive(36.30) upUseDrive(36.30) NAME upUseDrive - make a drive busy and ready for use. SYNOPSIS dinfo = upUseDrive (info, drive) D0 -90 A0 A1 APTR upUseDrive (APTR, char *); FUNCTION This function find out which device the drive given uses and open it. Then it will make the drive busy, that means CLI/WorkBench will not be able to use that drive until you unuse it. It's only you that can use it. This function are only made to give you a help to write a track crunched-file saver. INPUTS info - is the memory address you got from the upAllocCInfo() function. drive - is a pointer to the drive you want to use, ex. DF0:, RAD:. OUTPUTS dinfo - is a pointer to a structure used by the device. This structure includes a IOStdReq structure and a message port structure. If you get a zero back, an error occurs. You can see in the UI_ErrorNum field to see want went wrong. BUGS None known. SEE ALSO upUnuseDrive(), upSendCmd() --------------------------------------------------------------------------- I really hope you can use this library. See also the Unpack.IFF file to see how to construct your program. If you find any bugs in the library or if you have some crunchers there are not in the library, please send a bug report or the crunchers to me, thanks! See in the "WantedHelp" for more info! WE NEED YOUR HELP TO GET THIS LIBRARY EVEN BETTER, THANK YOU VERY MUCH! Thomas Neumann Member of the SHI Anti Virus Group. Kongensgade 78 3550 Slangerup Denmark E-Mail: tax@fiol.nbrock.dk